QuickDraw 3Dô 1.5d6 DR - Win32 Platform Preliminary Developers' Release
Preliminary Release Notes - August 26, 1996
This special release includes preliminary optimized and debug builds of QuickDraw 3D for Win32. Since this is a preliminary release it may not represent the type of performance you can expect in the final release.
This is a preliminary development release. It is intended for evaluation purposes only. No part of this release may be redistributed without permission from Apple Computer.
Welcome to QuickDraw 3D!
QuickDraw 3D is a platform independent 3D graphics library developed by Apple Computer. Enclosed, you will find the 1.5d6 DR release of QuickDraw 3D for Win32. Note: QuickDraw 3D 1.5d6 for Win32 is equivalent to 1.5d7 on Mac OS.
QuickDraw 3D goes beyond providing 3D graphics, it provides an integrated solution both for the end user and for developers. QuickDraw 3D encompasses a standard file format (3DMF), acceleration layer, input architecture, high level geometries, and extensibility.
QuickDraw 3D is a library for PowerPCô based computers running the MacOS and Pentiumô based computers running Windows 95ô or Windows NTô 3.51 and 4.0. The API is in C, with support for development using C++. QuickDraw 3D allows for immediate mode and retained rendering. The API is object based and provides a large number of geometry types. The file format accommodates both text and binary modes, with encoding for endianess so that files can be transported to other platforms and across the Internet. 3DMF parser code for several different platforms is available from our Web page at http://quickdraw3d.apple.com.
QuickDraw 3D for Win32 System Requirements
Pentium processor
Windows 95 or Windows NT (3.51 or 4.0b2)
A video board providing 256 color (8-bit) at 640x480 resolution. High Color (16-bit) or True Color (24-bit or 32-bit) video highly recommended.
Development System Requirements
Microsoft Visual C++ 4.x
MSVCR40D.DLL - the debug version of C runtime DLL which is included with Visual C++ 4.x
Using this QuickDraw 3D Win32 Preliminary Developer Release
There are two different builds of QuickDraw 3D for Win32. An optimized build and a debug build. These are located in the \Lib and \Lib\Debug directories respectively. This preliminary developer release of QuickDraw 3Dcurrently has no installer.
Make sure you clear out any old versions of QuickDraw 3D including QD3D.DLL, QD3D_D.DLL, RAVE.DLL, RAVE_D.DLL, QD3D_IR.Q3X, QD3D_IR_D.Q3X, QD3D_IR2.Q3X, and QD3D_IR2_D.Q3X.
Copy the contents of the QuickDraw 3D preliminary Win32 release to your hard drive.
Set you Lib and Include paths to reference the QuickDraw 3D Lib and Lib\Debug directories and Interfaces directory respectively. (Under Visual C++ this can be done from the Tools|Options|Directories dialog panel.)
Set your system's Path to reference the QuickDraw 3D Lib and Lib\Debug directories where the QuickDraw 3D DLLs are located.
Note: QuickDraw 3D loads plug-ins such as the Interactive Renderer from the same directory as the QuickDraw 3D library so it is important that you have QD3D_IR2.q3x in the same directory as QD3D.dll or QD3D_IR2_D.q3x in the same directory as QD3D_D.dll. You can copy either the optimized or debug DLLs to your Windows\System folder (Win95) or Windows\System32 directory (NT), but you must take care that you do not mix debug and optimized versions.
Lib, Include and Path can be also be set using environment variables (in Autoexec.bat on Win95 or in the System control panel on NT).
example:
Set LIB = %LIB%;c:\QD3D\LIB
Set INCLUDE = %INCLUDE%;c:\QD3D\Interfaces
Set PATH = %Path%;c:\QD3D\LIB;c:\QD3D\LIB\Debug
Feature Differences for Win32 Version of QuickDraw 3D
Pixmap Draw Context Only
Only the pixmap draw context is supported in this developer release of the QuickDraw 3D. The implication of this is that your application will be responsible for blitting the draw context to the screen. See "Implementing Double Buffering Using Pixmap Draw Context and GDI" below.
A Win32 specific draw context will be fully supported in a forthcoming developer release.
The QuickDraw 3D Pointing Device Manager
The QuickDraw 3D Pointing Device Manager API is not supported in the Win32 version of QuickDraw 3D.
Fixed Problems and Changes
Release d7 and d6
The d6 Windows 95/NT release is identical to the d7 release for MacOS. MacOS d6 was linked against the wrong library and was rebuilt as d7.
Also, d6 has a new version of the Interactive Renderer (QD3D_IR2.Q3X) with more loops optimized and bug fixes.
QuickDraw 3D
#1212783 DrawContext mask is relative to window origin and not drawing origin
#1212783 Fixed incorrect origin for Mask in draw context.
#1236379 Clearing respects mask
#1251484 Q3DrawContext_SetMask should allow null mask if maskstate is false
#1350972 win32Storage bug in iWin32Storage_Read
#1359648 Low mem crash in Q3Geometry_Submit
#1359972 Low mem - Q3Cone_New
#1359981 fix low mem error - Q3Cylinder_New
#1359991 fix low mem error - Q3Disk_New
#1360014 fix low mem error - Q3Ellipse_New
#1360018 fix low mem error - Q3Torus_New
#1364919 texture animation bug
#1366944 fix up failure cases in Interactive Renderer
#1367341 Immediate mode submission of attributes was not working.
#1368155 When Interactive Renderer does not load, we need to be more cautious as far as Q3InteractiveRenderer calls go.
#1369187 highlighting and texturing bug
#1372185 Problem when Engine creation fails in RAVE
#1372296 fix memory leak (#1372296)
#1372443 - The code that copies the Trimesh info was not checking for NULL edge and was therefore getting garbage.
#1373437 Mask not working correctly for draw contexts
#1373747 MacDrawContext blitting wrong with double-buffered, paned, monitor-crossing wind
#1374058: Added shadingUV attributes to output triangles (normalized from 0-1)
#1374260 Bug in TriGrid to Trimesh conversion
#1374892 - Light groups need a copy method, which does nothing, so that Object_Duplicate works for them. This should be inheriting from Group, so the bug remains open. This is just a workaround.
#1374895 - Save the context when QuickDraw 3D gets initialized and use it to force CFM to load extension in the same heap. This fixes a problem with Component Manager/QT 2.5.
#1374896 - When re-registering an attribute, we should post a warning, not an error. Added more Errors/Warnings to make it easier for developers to determine what went wrong.
#1379429 - Added SurfaceShader as mask type and to maskAll for attributeSet mask.
#1379429 - The mask would be updated even when the addition of attributes failed. Now we check for the value first.
#1369547 Internally the Viewer wasn't re-setting the camera button
#1369287 No drag in Viewer means no drag, disabled option key for drag
#1368149 Extension loading mechanism looks for extensions in the same place as the where the library is loaded from
#1369361 Orthographic camera had bad validation code in the debug case, firing assertion
#1368895: In Q3Pick_GetPickDetailData return default initialization values when pick detail data isn't present.
#1368661: In Q3Pick_GetPickDetailData return NULL for rootGroup, NULL for postions, 0 for depth when this pick detail data isn't present.
#1354659 - NURB patches were crashing
Improve small trimesh performance
#1368158: Fix MP support
RAVE
Fix logic-physical translation
Add ability to initialize cache context with self
Release d2
QuickDraw 3D
#1360746 made 1.5b2 compatible with QT2.5
Exported missing I/O functions
#1367881 - Aliases were being resolved before it was determined that the file was a QuickDraw 3D extension.
#1366467 - The ObjectSubclass routine was being too picky on the object type. It was generating an error when asking about the subtype of the parent class. For example, Q3DisplayGroup_GetType on a DisplayGroup would fail (and this worked on 1.0.x).
#1355057 - When the window was totally occluded, the DrawRegion was NULL and the code was not checking for that.
Wireframe was not using the DrawRegions properly
#1367858 - Hot angle for Spot Lights was not being set
edge data for trimesh is now honored.
RAVE
Handling cache initializing with itself is done correctly.
Known Problems in d7
The release build of the library for Windows (in "Lib" folder) is currently unstable do to a known bug in the renderer. We actively working to address this problem. The debug build (in "Lib\Debug") is much more solid.
Windows specific DrawContext are not in yet. Use pixmap workaround for now. (see "Implementing Double Buffering..." below)
On a memory protected OS you will access violations when using custom attributes/elements. (Fixed for next build)
8-bit has a set up time per window and may appear slow if opening and disposing of the window happens in quick succession.
Implementing Double Buffering Using Pixmap Draw Context and GDI
QuickDraw 3D applications using this developer release must use the generic pixmap draw context. A native Win32 draw context will be fully supported in a future developer release.
The basic method for managing a pixmap draw context is demonstrated in the enclosed QD3DSample application project. It consists of two main steps: Creating a new draw context for a view and rendering.
Creating a draw context for a view:
Create a memory device context compatible with the view window's DC and store a reference to it.
hdc = GetDC(theDocument->fWindow);
theDocument->fMemoryDC = CreateCompatibleDC(hdc);
Create an 16 or 32 bit device independent bitmap (DIB) and select it into the memory device context.
Create a new pixmap draw context which is parametrized to match the DIB. Set the pixmap draw context's image data pointer to the DIB's bitmap data. The draw context's doubleBufferState flag should be false.
This preliminary developer release includes debugging and optimized versions of the QuickDraw 3D DLLs. The debugging library requires MSVCR40D.DLL - the debug version of the Visual C++ 4.x C-runtime library DLL.
About QuickDraw 3D for Win32's MSVC shared runtime library dependency.
QuickDraw 3D has dependencies on the ANSI C-runtime library. In fact some QuickDraw 3D APIs pass C-runtime library data structures as parameters (e.g. Q3UnixStorage_New()). In order for these APIs to work properly the Win32 version of QuickDraw 3D is linked with the DLL version of the C-runtime library.
The release (optimized) build of QuickDraw 3D requires and is distributed with the non-debug, multithreaded DLL version of Microsoft's Visual C++ 4.z C-runtime library (MSVCRT40.DLL). It is our feeling that this library is the most popular and best supported version of the C-runtime libraries. (There is complete source for this library included with Visual C++.) Unfortunately we are not allowed to distribute the debug build of the MSVC C-runtime library DLL (MSVCR40D.DLL). You must have a license to Microsoft Visual C++ 4.x to obtain the debug DLL.
See also: Microsoft Knowledge Base Article Q94248 "Using the C Run-Time" and Visual C++ User's Guide - (Setting Compiler Options:Code Generation) "Use Run-Time Libarary".
What's In This Release?
In the Lib\Debug folder (the debug version of QuickDraw 3D)
QD3D_D.DLL - the debug version of the QuickDraw 3D 1.5 core library,
dependencies: MSVCR40D.DLL, QD3D_IR2_D.q3x and RAVE_D.DLL
QD3D_D.LIB - the import library for QD3D_D.DLL
QD3D_IR2_D.q3x - a preliminary debug build of QuickDraw 3D Interactive Renderer plug-in version 1.5
RAVE_D.DLL - a preliminary debug build of QuickDraw 3D Accelleration library version 1.5
RAVE_D.LIB - the import library for RAVE_D.DLL
3DViewer_d.DLL - a preliminary debug build of the 3D Viewer for Windows
3DViewer.LIB - the import library for 3DViewer.DLL
In the Interfaces folder
The public interfaces for QD3D.DLL and 3DViewer.DLL
In the Samples folder
QD3DSample - a simple application which demonstrates using the QuickDraw 3D core library to load and display 3D data. This sample implements double buffering using a pixmap draw context as described above.
ViewerSample - a simple example of using the QuickDraw 3D Viewer Controller in a Win32 application.
Documentation
The "Documentation" subdirectory of this release includes Adobe Acrobat PDF versions of the QuickDraw 3D reference "3D Graphics Programming With QuickDraw 3D", the preliminary "3D Metafile Reference" as well as two introductory articles from Apple technical journal develop. Even though the develop articles discuss using QuickDraw 3D with the MacOS most of the material contained therein is equally applicable to the Win32 version of QuickDraw 3D.
The Adobe Acrobat Reader for Windows is included in the "Documentation" directory.
"3D Graphics Programming With QuickDraw 3D" is available from Addison-Wesley Publishing Company. ISBN 0-201-48926-0
Redistribution
No part of this Preliminary Developer Release may be redistributed at this time.
Feedback
Please send bug reports to revans@apple.com. In the event that you have to report a problem please be sure to specify that you are using this 1.5d6 preliminary Win32 developer release and be sure to include a complete description of your PC system configuration including video board and video driver configuration.
Send your comments and feedback on this release to hopwood@apple.com.
Apple Computer's 3D technologies evangelist, Shawn Hopwood (hopwood@apple.com) is eager to work with developers. Contact Shawn with details of your product.
Thanks for choosing QuickDraw 3D, and good luck with your development efforts!!
